docz-cli 0.9.0 → 0.10.0

package/dist/{chunk-K3JRXIEV.js → chunk-26LVQHYL.js}

@@ -312,6 +312,301 @@ var DocSyncClient = class {
   }
 };
 
+// src/collab/text.ts
+import { createHash } from "crypto";
+function collabHash(content) {
+  return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+var CollabConflictError = class extends Error {
+  constructor(currentHash, baseHash) {
+    super(
+      `collaborative document changed since base_collab_hash (current: ${currentHash}, base: ${baseHash})`
+    );
+    this.currentHash = currentHash;
+    this.baseHash = baseHash;
+    this.name = "CollabConflictError";
+  }
+};
+var CollabBaseHashRequiredError = class extends Error {
+  constructor(currentHash) {
+    super(
+      `base_collab_hash is required unless force is explicitly enabled (current: ${currentHash})`
+    );
+    this.currentHash = currentHash;
+    this.name = "CollabBaseHashRequiredError";
+  }
+};
+function getYText(doc) {
+  return doc.getText("content");
+}
+function readText(doc) {
+  return getYText(doc).toString();
+}
+function replaceText(doc, nextContent, opts = {}) {
+  const ytext = getYText(doc);
+  const previous = ytext.toString();
+  const previousHash = collabHash(previous);
+  const baseHash = opts.baseHash;
+  if (!opts.force) {
+    if (!baseHash) {
+      throw new CollabBaseHashRequiredError(previousHash);
+    }
+    if (previousHash !== baseHash) {
+      throw new CollabConflictError(previousHash, baseHash);
+    }
+  }
+  doc.transact(() => {
+    ytext.delete(0, ytext.length);
+    if (nextContent) ytext.insert(0, nextContent);
+  }, opts.origin ?? "docz-cli");
+  return { previousHash, hash: collabHash(nextContent) };
+}
+
+// src/collab/types.ts
+var CollabUnknownError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CollabUnknownError";
+  }
+};
+var CollabPublishError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CollabPublishError";
+  }
+};
+
+// src/collab/room.ts
+import { randomUUID } from "crypto";
+import {
+  HocuspocusProvider,
+  HocuspocusProviderWebsocket
+} from "@hocuspocus/provider";
+import WebSocket from "ws";
+import * as Y from "yjs";
+
+// src/collab/roomName.ts
+function decodePath(path) {
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return path;
+  }
+}
+function normalizeCollabFilePath(path) {
+  const decoded = decodePath(path.trim()).replace(/\\/g, "/");
+  const parts = [];
+  for (const part of decoded.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") throw new Error("invalid collab file path");
+    parts.push(part);
+  }
+  return parts.join("/");
+}
+function buildCollabDocumentName(spaceId, filePath) {
+  const sid = spaceId.trim();
+  const normalizedPath = normalizeCollabFilePath(filePath);
+  if (!sid || !normalizedPath)
+    throw new Error("space id and file path are required");
+  return `${sid}:${normalizedPath}`;
+}
+
+// src/collab/room.ts
+function wsUrl(baseUrl) {
+  const u = new URL(baseUrl);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.pathname = "/collab";
+  u.search = "";
+  u.hash = "";
+  return u.toString();
+}
+function withTimeout(promise, ms, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CollabUnknownError(`${label} timed out after ${ms}ms`)),
+      ms
+    );
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+var CollabRoomClient = class {
+  doc = new Y.Doc();
+  provider = null;
+  websocketProvider = null;
+  openOptions = null;
+  pending = /* @__PURE__ */ new Map();
+  connected = false;
+  synced = false;
+  readOnly = false;
+  async open(options) {
+    const openOptions = {
+      ...options,
+      path: normalizeCollabFilePath(options.path),
+      timeoutMs: options.timeoutMs ?? 3e4
+    };
+    this.openOptions = openOptions;
+    const opened = new Promise((resolve, reject) => {
+      const websocketProvider = new HocuspocusProviderWebsocket({
+        url: wsUrl(openOptions.baseUrl),
+        WebSocketPolyfill: WebSocket,
+        parameters: {
+          space_id: openOptions.spaceId,
+          file_path: openOptions.path,
+          client: openOptions.client,
+          client_version: openOptions.clientVersion
+        }
+      });
+      this.websocketProvider = websocketProvider;
+      const provider = new HocuspocusProvider({
+        websocketProvider,
+        name: buildCollabDocumentName(openOptions.spaceId, openOptions.path),
+        document: this.doc,
+        token: () => openOptions.token,
+        onAuthenticated: () => {
+        },
+        onAuthenticationFailed: (data) => {
+          reject(
+            new CollabPublishError(
+              `collab authentication failed: ${data.reason}`,
+              "auth_failed"
+            )
+          );
+        },
+        onStatus: ({ status }) => {
+          this.connected = status === "connected";
+        },
+        onSynced: ({ state }) => {
+          this.synced = state;
+          if (state) resolve();
+        },
+        onStateless: ({ payload }) => {
+          this.handleStateless(payload);
+        },
+        onDisconnect: () => {
+          this.connected = false;
+        }
+      });
+      this.provider = provider;
+    });
+    await withTimeout(opened, openOptions.timeoutMs, "collab open");
+    return this.read();
+  }
+  read() {
+    if (!this.openOptions) throw new Error("collab room is not open");
+    const content = readText(this.doc);
+    return {
+      spaceId: this.openOptions.spaceId,
+      path: this.openOptions.path,
+      content,
+      collabHash: collabHash(content),
+      connected: this.connected && this.synced,
+      readOnly: this.readOnly
+    };
+  }
+  write(content, opts = {}) {
+    if (!this.openOptions) throw new Error("collab room is not open");
+    if (this.readOnly)
+      throw new CollabPublishError("collab room is read-only", "read_only");
+    const result = replaceText(this.doc, content, {
+      baseHash: opts.baseHash,
+      force: opts.force,
+      origin: this.openOptions.client
+    });
+    return {
+      spaceId: this.openOptions.spaceId,
+      path: this.openOptions.path,
+      previousHash: result.previousHash,
+      collabHash: result.hash
+    };
+  }
+  async publish(timeoutMs) {
+    if (!this.provider || !this.openOptions)
+      throw new Error("collab room is not open");
+    const reqId = randomUUID();
+    const ms = timeoutMs ?? this.openOptions.timeoutMs ?? 3e4;
+    const result = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        reject(
+          new CollabUnknownError(`collab publish ack timed out after ${ms}ms`)
+        );
+      }, ms);
+      this.pending.set(reqId, { resolve, reject, timer });
+    });
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "publish",
+        reqId,
+        client: this.openOptions.client,
+        client_version: this.openOptions.clientVersion
+      })
+    );
+    return result;
+  }
+  close() {
+    for (const [reqId, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(
+        new CollabUnknownError("collab room closed before publish ack")
+      );
+      this.pending.delete(reqId);
+    }
+    this.provider?.destroy();
+    this.websocketProvider?.destroy();
+    this.provider = null;
+    this.websocketProvider = null;
+    this.doc.destroy();
+  }
+  handleStateless(payload) {
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (!msg.reqId) return;
+    const pending = this.pending.get(msg.reqId);
+    if (!pending) return;
+    this.pending.delete(msg.reqId);
+    clearTimeout(pending.timer);
+    if (msg.type === "publish_ack" || msg.type === "recreate_after_delete_ack") {
+      if (!this.openOptions) {
+        pending.reject(
+          new CollabUnknownError("collab room closed before publish ack")
+        );
+        return;
+      }
+      pending.resolve({
+        spaceId: this.openOptions.spaceId,
+        path: this.openOptions.path,
+        ref: msg.ref || "",
+        contentRef: msg.content_ref || "",
+        externalBackup: msg.external_backup || ""
+      });
+      return;
+    }
+    pending.reject(
+      new CollabPublishError(
+        `collab publish failed${msg.code ? `: ${msg.code}` : ""}`,
+        msg.code
+      )
+    );
+  }
+};
+async function withCollabRoom(options, fn) {
+  const room = new CollabRoomClient();
+  try {
+    await room.open(options);
+    return await fn(room);
+  } finally {
+    room.close();
+  }
+}
+
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -347,6 +642,96 @@ function getConfigPath() {
 // src/commands.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
 import { basename } from "path";
+
+// src/collab/bridge.ts
+import readline from "readline";
+function send(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+async function startCollabBridge(openRoom) {
+  let room = null;
+  let cleanupObserver = null;
+  const rl = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  function attachObserver(nextRoom) {
+    cleanupObserver?.();
+    const ytext = nextRoom.doc.getText("content");
+    const observer = () => {
+      const content = ytext.toString();
+      send({ event: "document_change", content, hash: collabHash(content) });
+    };
+    ytext.observe(observer);
+    cleanupObserver = () => ytext.unobserve(observer);
+  }
+  function closeRoom() {
+    cleanupObserver?.();
+    cleanupObserver = null;
+    room?.close();
+    room = null;
+  }
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch (err) {
+      send({ event: "error", code: "bad_json", message: String(err) });
+      continue;
+    }
+    try {
+      if (req.method === "open") {
+        const target = String(req.params?.target ?? "");
+        closeRoom();
+        room = await openRoom(target);
+        attachObserver(room);
+        const current = room.read();
+        send({
+          id: req.id,
+          result: {
+            content: current.content,
+            hash: current.collabHash,
+            read_only: current.readOnly
+          }
+        });
+        send({
+          event: "opened",
+          content: current.content,
+          hash: current.collabHash
+        });
+      } else if (req.method === "local_change") {
+        if (!room) throw new Error("room is not open");
+        const content = String(req.params?.content ?? "");
+        const baseHash = req.params?.base_hash ? String(req.params.base_hash) : void 0;
+        const result = room.write(content, {
+          baseHash,
+          force: req.params?.force === true
+        });
+        send({ id: req.id, result: { hash: result.collabHash } });
+      } else if (req.method === "publish") {
+        if (!room) throw new Error("room is not open");
+        send({ id: req.id, result: await room.publish() });
+      } else if (req.method === "status") {
+        send({ id: req.id, result: room ? room.read() : { connected: false } });
+      } else if (req.method === "close") {
+        closeRoom();
+        send({ id: req.id, result: { ok: true } });
+      } else {
+        throw new Error(`unknown method: ${req.method}`);
+      }
+    } catch (err) {
+      send({
+        id: req.id,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  closeRoom();
+}
+
+// src/commands.ts
 function getClient() {
   const token = getToken();
   if (!token) {
@@ -357,6 +742,32 @@ function getClient() {
   }
   return new DocSyncClient(getBaseUrl(), token);
 }
+function getRequiredToken() {
+  const token = getToken();
+  if (!token) {
+    console.error(
+      "Error: No token configured.\nRun `docz login` or set DOCSYNC_API_TOKEN environment variable."
+    );
+    process.exit(1);
+  }
+  return token;
+}
+async function buildCollabOpenOptions(target, opts = {}) {
+  const api = getClient();
+  const { spaceId, path } = await resolveTarget(api, [target]);
+  if (!path) {
+    throw new Error("file path is required for collaborative editing");
+  }
+  return {
+    baseUrl: getBaseUrl(),
+    token: getRequiredToken(),
+    spaceId,
+    path,
+    client: opts.client ?? "docz-cli",
+    clientVersion: opts.clientVersion ?? "0.10.0",
+    timeoutMs: opts.timeout
+  };
+}
 function parseTarget(args) {
   if (args.length === 0) {
     console.error(
@@ -887,6 +1298,124 @@ function registerCommands(program) {
     const ref = await client.getFileRef(spaceId, path);
     console.log(ref.url);
   });
+  const collab = program.command("collab").description("Collaborative editing via Docz realtime rooms");
+  collab.command("cat").description(
+    "Read collaborative document \u2014 docz collab cat <space>:<path> or <url>"
+  ).argument("<target>", "space:path or short URL").option("--raw", "Output raw content only").option("--timeout <ms>", "Open timeout in milliseconds", Number).action(
+    async (target, opts) => {
+      const open = await buildCollabOpenOptions(target, {
+        timeout: opts.timeout
+      });
+      await withCollabRoom(open, async (room) => {
+        const result = room.read();
+        if (!opts.raw) {
+          console.error(`collab_hash: ${result.collabHash}`);
+          console.error(`read_only: ${result.readOnly ? "true" : "false"}`);
+          console.error("---");
+        }
+        process.stdout.write(result.content);
+      });
+    }
+  );
+  collab.command("write").description(
+    "Write collaborative document \u2014 docz collab write <space>:<path> <content>"
+  ).argument("<target>", "space:path or short URL").argument("<content>", "File content (or - for stdin)").option("--base-collab-hash <hash>", "Hash returned by docz collab cat").option("--force", "Skip collaborative hash conflict detection").option("--no-publish", "Only update realtime room, do not flush to repo").option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(
+    async (target, content, opts) => {
+      const open = await buildCollabOpenOptions(target, {
+        timeout: opts.timeout
+      });
+      const body = content === "-" ? await readStdin() : content;
+      if (Buffer.byteLength(body, "utf-8") > MAX_SAVE_SIZE) {
+        console.error(
+          "Error: content exceeds 2MB limit. Use `docz upload` for large files."
+        );
+        process.exit(1);
+      }
+      try {
+        await withCollabRoom(open, async (room) => {
+          const write = room.write(body, {
+            baseHash: opts.baseCollabHash,
+            force: opts.force
+          });
+          if (opts.publish === false) {
+            console.log(
+              `Updated collaborative room (collab_hash: ${write.collabHash})`
+            );
+            return;
+          }
+          const published = await room.publish(opts.timeout);
+          console.log(
+            `Published: ${published.path} (ref: ${published.ref}, collab_hash: ${write.collabHash})`
+          );
+          if (published.externalBackup) {
+            console.log(`External backup: ${published.externalBackup}`);
+          }
+        });
+      } catch (err) {
+        if (err instanceof CollabConflictError) {
+          console.error(
+            `Error: collaborative document changed. Re-read and retry. current=${err.currentHash} base=${err.baseHash}`
+          );
+          process.exit(1);
+        }
+        if (err instanceof CollabBaseHashRequiredError) {
+          console.error(
+            `Error: --base-collab-hash is required unless --force is set. Re-read first to get the latest hash. current=${err.currentHash}`
+          );
+          process.exit(1);
+        }
+        if (err instanceof CollabUnknownError) {
+          console.error(
+            `Unknown state: ${err.message}. The server may have processed the publish; please re-read before retrying.`
+          );
+          process.exit(75);
+        }
+        throw err;
+      }
+    }
+  );
+  collab.command("publish").description(
+    "Flush collaborative document to repo \u2014 docz collab publish <space>:<path>"
+  ).argument("<target>", "space:path or short URL").option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(async (target, opts) => {
+    const open = await buildCollabOpenOptions(target, {
+      timeout: opts.timeout
+    });
+    try {
+      await withCollabRoom(open, async (room) => {
+        const result = await room.publish(opts.timeout);
+        console.log(`Published: ${result.path} (ref: ${result.ref})`);
+        if (result.externalBackup) {
+          console.log(`External backup: ${result.externalBackup}`);
+        }
+      });
+    } catch (err) {
+      if (err instanceof CollabUnknownError) {
+        console.error(
+          `Unknown state: ${err.message}. The server may have processed the publish; please re-read before retrying.`
+        );
+        process.exit(75);
+      }
+      throw err;
+    }
+  });
+  collab.command("bridge").description("Start local JSONL bridge for terminal editors").option("--client <name>", "Client name sent to Docz", "docz.nvim").option(
+    "--client-version <version>",
+    "Client version sent to Docz",
+    "0.10.0"
+  ).option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(
+    async (opts) => {
+      await startCollabBridge(async (target) => {
+        const open = await buildCollabOpenOptions(target, {
+          client: opts.client,
+          clientVersion: opts.clientVersion,
+          timeout: opts.timeout
+        });
+        const room = new CollabRoomClient();
+        await room.open(open);
+        return room;
+      });
+    }
+  );
   program.command("diff").description(
     "Show changes \u2014 docz diff <space>[:<path>] <commit> [<from>] or <url> <commit> [<from>]"
   ).argument("<target>", "space or space:path or short URL").argument("<to>", "Commit hash").argument("[from]", "From commit hash (default: to^)").action(async (target, to, from) => {
@@ -915,6 +1444,10 @@ function registerCommands(program) {
 export {
   ConflictError,
   DocSyncClient,
+  CollabConflictError,
+  CollabBaseHashRequiredError,
+  CollabUnknownError,
+  withCollabRoom,
   getBaseUrl,
   getToken,
   parseExpires,
@@ -922,4 +1455,4 @@ export {
   markdownImageRef,
   registerCommands
 };
-//# sourceMappingURL=chunk-K3JRXIEV.js.map
+//# sourceMappingURL=chunk-26LVQHYL.js.map